/*
 * Copyright (c) 2007 jMouse Gestures
 * All rights reserved.
 *
 * Redistribution and use in source and binary forms, with or without
 * modification, are permitted provided that the following conditions are
 * met:
 *
 * * Redistributions of source code must retain the above copyright
 *   notice, this list of conditions and the following disclaimer.
 *
 * * Redistributions in binary form must reproduce the above copyright
 *   notice, this list of conditions and the following disclaimer in the
 *   documentation and/or other materials provided with the distribution.
 *
 * * Neither the name of 'jMouse Gestures' nor the names of its contributors
 *   may be used to endorse or promote products derived from this software
 *   without specific prior written permission.
 *
 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
 * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
 * TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
 * PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR
 * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
 * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
 * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
 * PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
 * LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
 * NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
 * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 */

package com.jmg.mouse;

import java.io.Serializable;
import java.util.ArrayList;
import java.util.Collection;
import com.jmg.gesture.event.GestureListener;
import com.jmg.gesture.GestureManager;
import com.jmg.space.JMGLocation;
import com.jmg.space.Location;


/**
 * MouseMovementRecorder class records <code>MouseMovements</code> while
 * gestures are being performed.  These <code>MouseMovements</code> can then
 * be used to checks for valid gestures having been performed.
 *
 * @author  Christopher Martin
 * @version $Id: MouseMovementRecorder.java 13 2007-05-24 12:13:13Z GentlemanHal $
 */
public class MouseMovementRecorder implements 
    GestureListener,
    Serializable
{
    /** Serial Version UID */
    private static final long serialVersionUID = 1L;
    
    /** Default value for how many events should be received before updating. */
    public static final int DEFAULT_SENSITIVITY = 6;
    
    private int sensitivity;
    
    private transient Collection<MouseMovement> mouseMovements;

    private transient final MutableLocation previous = new MutableLocation();
    
    private transient int updates = 0;
    
    
    
    
    
    /** 
     * Creates a new instance of <code>MouseMovementRecorder</code> using a
     * synchronized <code>ArrayList</code> as the backing store for the
     * <code>MouseMovements</code>. 
     */
    public MouseMovementRecorder() {
        this(new ArrayList<MouseMovement>());
    }
    
    /**
     * Creates a new instance of <code>MouseMovementRecorder</code>.
     *
     * @param  mouseMovements The backing list for the mouse movements.
     * @throws java.lang.IllegalArgumentException If a <code>null</code> argument 
     *         is passed.
     */
    public MouseMovementRecorder(Collection<MouseMovement> mouseMovements) 
        throws IllegalArgumentException
    {
        if (null == mouseMovements) {
            throw new IllegalArgumentException("mouseMovements was null!");
        }
        
        
        this.mouseMovements = mouseMovements;
        
        sensitivity = DEFAULT_SENSITIVITY;
    }
    
    
    
    

    /**
     * Sets how many events this instance receives before it updates the
     * gestures location.
     * 
     * @param  sensitivity The number of events to receive before 
     *         updating.
     * @throws java.lang.IllegalArgumentException If a value less than or equal
     *         to zero is passed.
     * @see    #getSensitivity
     */
    public void setSensitivity(final int sensitivity) 
        throws IllegalArgumentException
    {
        if (sensitivity <= 0) {
            throw new IllegalArgumentException("sensitivity must be > 0! " + sensitivity);
        }
        
        
        this.sensitivity = sensitivity;
    }
    
    /**
     * Returns how many events this instance receives before updating the
     * gestures location.
     * 
     * @return The number of events that must be received.
     * @see    #setSensitivity(int)
     */
    public int getSensitivity() {
        return sensitivity;
    }
    
    
    
    
    
    /**
     * Sets the starting location of the gesture.
     * <p>
     * <strong>This method should never be called manually.</strong>
     * </p>
     * 
     * @param when The time this event happened.
     * @param where The location this event happened.
     * @param manager The manager that detected this event.
     */
    public void gestureStarted(long when, Location where, GestureManager<?> manager) {
        mouseMovements.clear();
        
        previous.update(where);
    }

    /**
     * Creates a <code>MouseMovement</code> and adds it to the array.
     * <p>
     * <strong>This method should never be called manually.</strong>
     * </p>
     * 
     * @param when The time this event happened.
     * @param where The location this event happened.
     * @param manager The manager that detected this event.
     */
    public void gestureMovement(long when, Location where, GestureManager<?> manager) {
        updates++;
        
        if (updates >= sensitivity) {
            mouseMovements.add(manager.createFrameIndependantMovement(previous, where));
            
            previous.update(where);
            updates = 0;
        }
    }

    /**
     * Gets the Manager to check for a performed gesture.
     * <p>
     * <strong>This method should never be called manually.</strong>
     * </p>
     * 
     * @param when The time this event happened.
     * @param where The location this event happened.
     * @param manager The manager that detected this event.
     */
    public void gestureFinished(long when, Location where, GestureManager<?> manager) {
        previous.update(where);
        
        manager.checkForPerformedGesture(mouseMovements);
    }
    
    
    
    

    /**
     * Returns a <code>String</code> representation of the object.
     * 
     * @return a <code>String</code> representation.
     */
    @Override
    public String toString() {
        StringBuilder buf = new StringBuilder(38);
        
        buf.append(getClass().getName());
        buf.append("[sensitivity=").append(sensitivity); 
        buf.append(']');
        
        return buf.toString();
    }
    
    /**
     * Indicates whether some other object is "equal to" this one.
     * 
     * @param  obj The reference object with which to compare.
     * @return <code>true</code> if this object is the same as the obj
     *         argument, <code>false</code> otherwise.
     */
    @Override
    public boolean equals(Object obj) {
        if (this == obj) {
            return true;
        }
        
        if (!(obj instanceof MouseMovementRecorder)) {
            return false;
        }
        
        return ((MouseMovementRecorder) obj).sensitivity == sensitivity;
    }

    /**
     * Returns a hash code value for the object.
     * 
     * @return a hash code value for this object.
     */
    @Override
    public int hashCode() {
        return sensitivity;
    }
    
    
    
    
    
    /**
     * MutableLocation class.
     *
     * @author Christopher Martin
     */
    private class MutableLocation extends JMGLocation {
        /** Serial Version UID. */
        private static final long serialVersionUID = 1L;
        
        /**
         * Updates this <code>Location</code> to be the same coordinates as the 
         * given <code>Location</code>.
         * 
         * @param loc The Location that holds the values to update too.
         */
        public void update(Location loc) {
            this.x = loc.getX();
            this.y = loc.getY();
            this.z = loc.getZ();
        }
    }
    
}
